home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 January: Technology Seed / Jan. '98 ATS.toast / QuickTime™ 3.0b11 / QTPublicInterfaces / CIncludes / LocationManager.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-01-12  |  10.6 KB  |  367 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        LocationManager.h
  3.  
  4.      Contains:    LocationManager (manage preferences for different physical Locations)
  5.  
  6.      Version:    Technology:    System 7.6
  7.                  Release:    QuickTime 3.0 Beta
  8.  
  9.      Copyright:    © 1995-1997 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. */
  18. #ifndef __LOCATIONMANAGER__
  19. #define __LOCATIONMANAGER__
  20.  
  21. #ifndef __APPLEEVENTS__
  22. #include <AppleEvents.h>
  23. #endif
  24. #ifndef __COMPONENTS__
  25. #include <Components.h>
  26. #endif
  27. #ifndef __DIALOGS__
  28. #include <Dialogs.h>
  29. #endif
  30. #ifndef __PROCESSES__
  31. #include <Processes.h>
  32. #endif
  33. #ifndef __STANDARDFILE__
  34. #include <StandardFile.h>
  35. #endif
  36.  
  37.  
  38.  
  39. #if PRAGMA_ONCE
  40. #pragma once
  41. #endif
  42.  
  43. #ifdef __cplusplus
  44. extern "C" {
  45. #endif
  46.  
  47. #if PRAGMA_IMPORT
  48. #pragma import on
  49. #endif
  50.  
  51. #if PRAGMA_STRUCT_ALIGN
  52.     #pragma options align=mac68k
  53. #elif PRAGMA_STRUCT_PACKPUSH
  54.     #pragma pack(push, 2)
  55. #elif PRAGMA_STRUCT_PACK
  56.     #pragma pack(2)
  57. #endif
  58.  
  59. /* Location Manager API Support -------------------------------------------------------------------- */
  60. /* A Location Token uniquely identifies a Location on a machine... */
  61.  
  62. typedef struct OpaqueALMToken*             ALMToken;
  63. #define kALMNoLocationToken    ((ALMToken)(-1))  // ALMToken of "off" Location...
  64.  
  65. enum {
  66.     kALMLocationNameMaxLen        = 31,                            /* name (actually imposed by file system)... */
  67.     kALMMaxLocations            = 16,                            /* arbitrary limit enforced by Location Manager... */
  68.     kALMNoLocationIndex            = -1                            /* index for the "off" Location (kALMNoLocationToken)... */
  69. };
  70.  
  71. typedef Str31                             ALMLocationName;
  72. /* Returned from ALMConfirmName... */
  73. typedef SInt16                             ALMConfirmChoice;
  74.  
  75. enum {
  76.     kALMConfirmRename            = 1,
  77.     kALMConfirmReplace            = 2
  78. };
  79.  
  80. /* ALMConfirmName dialog item numbers for use in callbacks (ALM 2.0)... */
  81.  
  82.  
  83. enum {
  84.     kALMDuplicateRenameButton    = 1,                            /* if Window refcon is kALMDuplicateDialogRefCon... */
  85.     kALMDuplicateReplaceButton    = 2,
  86.     kALMDuplicateCancelButton    = 3,
  87.     kALMDuplicatePromptText        = 5
  88. };
  89.  
  90.  
  91. enum {
  92.     kALMRenameRenameButton        = 1,                            /* if Window refcon is kALMRenameDialogRefCon... */
  93.     kALMRenameCancelButton        = 2,
  94.     kALMRenameEditText            = 3,
  95.     kALMRenamePromptText        = 4
  96. };
  97.  
  98. /* Refcons of two windows in ALMConfirmName (ALM 2.0)... */
  99.  
  100.  
  101. enum {
  102.     kALMDuplicateDialogRefCon    = FOUR_CHAR_CODE('dupl'),
  103.     kALMRenameDialogRefCon        = FOUR_CHAR_CODE('rnam')
  104. };
  105.  
  106. /* Callback routine for Location awareness (mimics AppleEvents) in non-application code... */
  107.  
  108. typedef CALLBACK_API( void , ALMNotificationProcPtr )(AppleEvent *theEvent);
  109. typedef STACK_UPP_TYPE(ALMNotificationProcPtr)                     ALMNotificationUPP;
  110. enum { uppALMNotificationProcInfo = 0x000000C0 };                 /* pascal no_return_value Func(4_bytes) */
  111. #define NewALMNotificationProc(userRoutine)                     (ALMNotificationUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppALMNotificationProcInfo, GetCurrentArchitecture())
  112. #define CallALMNotificationProc(userRoutine, theEvent)             CALL_ONE_PARAMETER_UPP((userRoutine), uppALMNotificationProcInfo, (theEvent))
  113. /* Notification AppleEvents sent to apps/registered code...  */
  114.  
  115. enum {
  116.     kAELocationChangedNoticeKey    = FOUR_CHAR_CODE('walk'),        /* Current Location changed... */
  117.     kAELocationRescanNoticeKey    = FOUR_CHAR_CODE('trip')        /* Location created/renamed/deleted... */
  118. };
  119.  
  120. /* ALMSwitchToLocation masks... */
  121.  
  122. typedef SInt32                             ALMSwitchActionFlags;
  123.  
  124. enum {
  125.     kALMDefaultSwitchFlags        = 0x00000000,                    /* No special action to take... */
  126.     kALMDontShowStatusWindow    = 0x00000001,                    /* Suppress "switching" window... */
  127.     kALMSignalViaAE                = 0x00000002                    /* Switch by sending Finder AppleEvent... */
  128. };
  129.  
  130. /* Parameters for Get/Put/Merge Location calls... */
  131.  
  132. typedef const OSType *                    ConstALMModuleTypeListPtr;
  133.  
  134. enum {
  135.     kALMAddAllOnSimple            = 0,                            /* Add all single-instance, non-action modules... */
  136.     kALMAddAllOff                = -1                            /* Add all modules but turn them off... */
  137. };
  138.  
  139. /* Item numbers for use in Get/Put/Merge Location filters... */
  140.  
  141.  
  142. enum {
  143.     kALMLocationSelectButton    = 1,
  144.     kALMLocationCancelButton    = 2,
  145.     kALMLocationBalloonHelp        = 3,
  146.     kALMLocationLocationList    = 7,
  147.     kALMLocationLocationNameEdit = 10,
  148.     kALMLocationPromptText        = 11
  149. };
  150.  
  151.  
  152. enum {
  153.     kALMLocationSaveButton        = kALMLocationSelectButton
  154. };
  155.  
  156. /* Location Manager Module API Support ------------------------------------------------------------- */
  157.  
  158. /* ALMGetScriptInfo stuff... */
  159.  
  160.  
  161. enum {
  162.     kALMScriptInfoVersion        = 2                                /* Customarily put in resource for localization... */
  163. };
  164.  
  165.  
  166. struct ALMScriptManagerInfo {
  167.     SInt16                             version;                    /* Set to kALMScriptInfoVersion... */
  168.     SInt16                             scriptCode;
  169.     SInt16                             regionCode;
  170.     SInt16                             langCode;
  171.     SInt16                             fontNum;
  172.     SInt16                             fontSize;
  173. };
  174. typedef struct ALMScriptManagerInfo        ALMScriptManagerInfo;
  175. typedef ALMScriptManagerInfo *            ALMScriptManagerInfoPtr;
  176. /*
  177.    Alternate form of ScriptInfo is easier to localize in resources; it is used extensively in
  178.    samples and internally, so....
  179. */
  180.  
  181. struct ALMAltScriptManagerInfo {
  182.     SInt16                             version;
  183.     SInt16                             scriptCode;
  184.     SInt16                             regionCode;
  185.     SInt16                             langCode;
  186.     SInt16                             fontSize;
  187.     Str63                             fontName;
  188. };
  189. typedef struct ALMAltScriptManagerInfo    ALMAltScriptManagerInfo;
  190. typedef ALMAltScriptManagerInfo *        ALMAltScriptManagerInfoPtr;
  191. typedef ALMAltScriptManagerInfoPtr *    ALMAltScriptManagerInfoHandle;
  192.  
  193. enum {
  194.     kALMAltScriptManagerInfoRsrcType = FOUR_CHAR_CODE('trip'),
  195.     kALMAltScriptManagerInfoRsrcID = 0
  196. };
  197.  
  198. /* Reboot information used on ALMSetCurrent (input/output parameter)... */
  199.  
  200.  
  201. typedef UInt32                             ALMRebootFlags;
  202.  
  203. enum {
  204.     kALMNoChange                = 0,
  205.     kALMAvailableNow            = 1,
  206.     kALMFinderRestart            = 2,
  207.     kALMProcesses                = 3,
  208.     kALMExtensions                = 4,
  209.     kALMWarmBoot                = 5,
  210.     kALMColdBoot                = 6,
  211.     kALMShutdown                = 7
  212. };
  213.  
  214. /*
  215.    File types and signatures...
  216.    Note: auto-routing of modules will not be supported for 'thng' files...
  217. */
  218.  
  219.  
  220. enum {
  221.     kALMFileCreator                = FOUR_CHAR_CODE('fall'),        /* Creator of Location Manager files... */
  222.     kALMComponentModuleFileType    = FOUR_CHAR_CODE('thng'),        /* Type of a Component Manager Module file [v1.0]... */
  223.     kALMComponentStateModuleFileType = FOUR_CHAR_CODE('almn'),    /* Type of a CM 'state' Module file... */
  224.     kALMComponentActionModuleFileType = FOUR_CHAR_CODE('almb'),    /* Type of a CM 'action' Module file... */
  225.     kALMCFMStateModuleFileType    = FOUR_CHAR_CODE('almm'),        /* Type of a CFM 'state' Module file... */
  226.     kALMCFMActionModuleFileType    = FOUR_CHAR_CODE('alma')        /* Type of a CFM 'action' Module file... */
  227. };
  228.  
  229. /* Component Manager 'thng' info... */
  230.  
  231.  
  232. enum {
  233.     kALMComponentRsrcType        = FOUR_CHAR_CODE('thng'),
  234.     kALMComponentType            = FOUR_CHAR_CODE('walk')
  235. };
  236.  
  237. /* CFM Modules require a bit of information (replacing some of the 'thng' resource)... */
  238.  
  239.  
  240. enum {
  241.     kALMModuleInfoRsrcType        = FOUR_CHAR_CODE('walk'),
  242.     kALMModuleInfoOriginalVersion = 0
  243. };
  244.  
  245. /* These masks apply to the "Flags" field in the 'thng' or 'walk' resource... */
  246.  
  247.  
  248. enum {
  249.     kALMMultiplePerLocation        = 0x00000001,                    /* Module can be added more than once to a Location... */
  250.     kALMDescriptionGetsStale    = 0x00000002                    /* Descriptions may change though the setting didn't...  */
  251. };
  252.  
  253. /* Misc stuff for older implementations ------------------------------------------------------------ */
  254.  
  255. #if OLDROUTINENAMES
  256. /* Old error codes for compatibility - new names are in Errors interface... */
  257.  
  258. enum {
  259.     ALMInternalErr                = -30049,                        /* use kALMInternalErr */
  260.     ALMLocationNotFound            = -30048,                        /* use kALMLocationNotFoundErr */
  261.     ALMNoSuchModuleErr            = -30047,                        /* use kALMNoSuchModuleErr */
  262.     ALMModuleCommunicationErr    = -30046,                        /* use kALMModuleCommunicationErr */
  263.     ALMDuplicateModuleErr        = -30045,                        /* use kALMDuplicateModuleErr */
  264.     ALMInstallationErr            = -30044,                        /* use kALMInstallationErr */
  265.     ALMDeferSwitchErr            = -30043                        /* use kALMDeferSwitchErr */
  266. };
  267.  
  268. /* Old ALMConfirmName constants... */
  269.  
  270.  
  271. enum {
  272.     ALMConfirmRenameConfig        = kALMConfirmRename,
  273.     ALMConfirmReplaceConfig        = kALMConfirmReplace
  274. };
  275.  
  276. /* Old AppleEvents... */
  277.  
  278.  
  279. enum {
  280.     kAELocationNotice            = kAELocationChangedNoticeKey
  281. };
  282.  
  283. typedef ALMScriptManagerInfo             ALMScriptMgrInfo;
  284. typedef UInt32                             ALMComponentFlagsEnum;
  285. #endif  /* OLDROUTINENAMES */
  286.  
  287. /* Location Manager API ---------------------------------------------------------------------------- */
  288.  
  289. /* The following 7 routines are present if gestaltALMAttr has bit gestaltALMPresent set... */
  290.  
  291. EXTERN_API( OSErr )
  292. ALMGetCurrentLocation            (SInt16 *                index,
  293.                                  ALMToken *                token,
  294.                                  ALMLocationName         name)                                THREEWORDINLINE(0x303C, 0x0600, 0xAAA4);
  295.  
  296. EXTERN_API( OSErr )
  297. ALMGetIndLocation                (SInt16                 index,
  298.                                  ALMToken *                token,
  299.                                  ALMLocationName         name)                                THREEWORDINLINE(0x303C, 0x0501, 0xAAA4);
  300.  
  301. EXTERN_API( OSErr )
  302. ALMCountLocations                (SInt16 *                locationCount)                        THREEWORDINLINE(0x303C, 0x0202, 0xAAA4);
  303.  
  304. EXTERN_API( OSErr )
  305. ALMSwitchToLocation                (ALMToken                 newLocation,
  306.                                  ALMSwitchActionFlags     switchFlags)                        THREEWORDINLINE(0x303C, 0x0403, 0xAAA4);
  307.  
  308. EXTERN_API( OSErr )
  309. ALMRegisterNotifyProc            (ALMNotificationUPP     notificationProc,
  310.                                  const ProcessSerialNumber * whichPSN)                        THREEWORDINLINE(0x303C, 0x0404, 0xAAA4);
  311.  
  312. EXTERN_API( OSErr )
  313. ALMRemoveNotifyProc                (ALMNotificationUPP     notificationProc,
  314.                                  const ProcessSerialNumber * whichPSN)                        THREEWORDINLINE(0x303C, 0x0405, 0xAAA4);
  315.  
  316. EXTERN_API( OSErr )
  317. ALMConfirmName                    (ConstStr255Param         message,
  318.                                  Str255                 theName,
  319.                                  ALMConfirmChoice *        choice,
  320.                                  ModalFilterUPP         filter)                                THREEWORDINLINE(0x303C, 0x0806, 0xAAA4);
  321.  
  322. /* The following 3 routines are present if gestaltALMAttr has bit gestaltALMHasSFLocation set... */
  323.  
  324. EXTERN_API( OSErr )
  325. ALMPutLocation                    (ConstStr255Param         prompt,
  326.                                  ALMLocationName         name,
  327.                                  SInt16                 numTypes,
  328.                                  ConstALMModuleTypeListPtr  typeList,
  329.                                  ModalFilterYDUPP         filter,
  330.                                  void *                    yourDataPtr)                        THREEWORDINLINE(0x303C, 0x0B07, 0xAAA4);
  331.  
  332. EXTERN_API( OSErr )
  333. ALMGetLocation                    (ConstStr255Param         prompt,
  334.                                  ALMLocationName         name,
  335.                                  ModalFilterYDUPP         filter,
  336.                                  void *                    yourDataPtr)                        THREEWORDINLINE(0x303C, 0x0808, 0xAAA4);
  337.  
  338. EXTERN_API( OSErr )
  339. ALMMergeLocation                (ConstStr255Param         prompt,
  340.                                  ALMLocationName         name,
  341.                                  SInt16                 numTypes,
  342.                                  ConstALMModuleTypeListPtr  typeList,
  343.                                  ModalFilterYDUPP         filter,
  344.                                  void *                    yourDataPtr)                        THREEWORDINLINE(0x303C, 0x0B09, 0xAAA4);
  345.  
  346.  
  347. #if PRAGMA_STRUCT_ALIGN
  348.     #pragma options align=reset
  349. #elif PRAGMA_STRUCT_PACKPUSH
  350.     #pragma pack(pop)
  351. #elif PRAGMA_STRUCT_PACK
  352.     #pragma pack()
  353. #endif
  354.  
  355. #ifdef PRAGMA_IMPORT_OFF
  356. #pragma import off
  357. #elif PRAGMA_IMPORT
  358. #pragma import reset
  359. #endif
  360.  
  361. #ifdef __cplusplus
  362. }
  363. #endif
  364.  
  365. #endif /* __LOCATIONMANAGER__ */
  366.  
  367.